<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>RVM : Adding a New GC</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            RVM : Adding a New GC
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jun 30, 2008 by <font color="#0050B2">steveblackburn</font>.
				    </div>

				    <h1><a name="AddingaNewGC-Overview"></a>Overview</h1>

<p>This document describes how to add a new garbage collector to Jikes RVM.&nbsp; We don't address how to design a new GC algorithm, just how to add a "new" GC to the system and then build it.&nbsp; We do this by cloning an existing GC.&nbsp; We leave it to you to design your own GC&#33;</p>

<h2><a name="AddingaNewGC-"></a></h2>


<h1><a name="AddingaNewGC-Prerequisites"></a>Prerequisites</h1>

<p>Ensure that you have got a clean copy of the <a href="Get The Source.html" title="Get The Source">source</a> (either a recent release or the svn head) and can correctly and successfully build one of the base garbage collectors.&nbsp; There's little point in trying to build your own until you can reliably build an existing one.&nbsp; I suggest you start with MarkSweep, and that you use the <a href="Using buildit.html" title="Using buildit">buildit</a> script:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ bin/buildit &lt;targetmachine&gt; BaseBase MarkSweep
</pre>
</div></div>
<p>&nbsp;Then test your GC:</p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<p>$ bin/buildit &lt;targetmachine&gt; &#45;t gctest BaseBase MarkSweep</p>
</div></div>
<p>&nbsp;You should have seen some output like this:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
test:
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] InlineAllocation (<span class="code-keyword">default</span>) : SUCCESS
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] ReferenceTest (<span class="code-keyword">default</span>) : SUCCESS
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] ReferenceStress (<span class="code-keyword">default</span>) : SUCCESS
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] FixedLive (<span class="code-keyword">default</span>) : SUCCESS
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] LargeAlloc (<span class="code-keyword">default</span>) : SUCCESS
     [echo] Test Result <span class="code-keyword">for</span> [BaseBaseMarkSweep|gctest] Exhaust (<span class="code-keyword">default</span>) : SUCCESS  
</pre>
</div></div>
<p>If this is not working, you should probably go and (re) read the <a href="Care and Feeding.html" title="Care and Feeding">section in the user guide</a> on how to build and run the VM.</p>

<h1><a name="AddingaNewGC-CloningtheMarkSweepGC"></a>Cloning the MarkSweep GC</h1>

<p>&nbsp;The best way to do this is in eclipse or a similar tool (see <a href="Editing JikesRVM in an IDE.html" title="Editing JikesRVM in an IDE">here</a> for how to work with eclipse):</p>
<ol>
	<li>Clone the <em>org.mmtk.plan.marksweep</em> as <em>org.mmtk.plan.</em><b><em>mygc</em></b>
	<ul>
		<li>You can do this with <b>Eclipse</b>:
		<ol>
			<li>Navigagte to <em>org.mmtk.plan.marksweep</em> (within <em>MMTk/src</em>)</li>
			<li>Right click over <em>org.mmtk.plan.marksweep</em> and select "Copy"</li>
			<li>Right click again, and select "Paste", and name the target <em>org.mmtk.plan.</em><b><em>mygc</em></b> (or whatever you like)</li>
			<li>This will have cloned the marksweep GC in a new package called <em>org.mmtk.plan.mygc</em></li>
		</ol>
		</li>
		<li>or <b>by hand</b>:
		<ol>
			<li>Copy the directory <em>MMTk/org/mmtk/plan/marksweep</em> to <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b></li>
			<li>Edit each file within <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b> and change its package declaration to <em>org.mmtk.plan.</em><b><em>mygc</em></b></li>
		</ol>
		</li>
		<li>We can leave the GC called "MS" for now (the file names will all be <em>MMTk/org/mmtk/plan/</em><b><em>mygc</em></b><em>/MS*.java)</em></li>
	</ul>
	</li>
	<li>Clone the BaseBaseMarkSweep.properties file as <em>BaseBase</em><b><em>MyGC</em></b><em>.properties</em>:
	<ol>
		<li>Go to <em>build/configs</em>, and right click over <em>BaseBaseMarkSweep.properties</em>, and select "Copy"</li>
		<li>Right click and select "Paste", and paste as <em>BaseBaseMyGC.properties</em></li>
		<li>Edit BaseBaseMyGC.properties, changing the text: "<em>config.mmtk.plan=org.mmtk.plan.</em><em>marksweep</em><em>.MS</em>" to "<em>config.mmtk.plan=org.mmtk.plan.</em><b><em>mygc</em></b><em>.MS</em>"</li>
	</ol>
	</li>
	<li>Now test your new GC:</li>
</ol>


<div class="panel" style="border-width: 1px;"><div class="panelContent">
<p>$ bin/buildit &lt;targetmachine&gt; &#45;t gctest BaseBase <b>MyGC</b></p>
</div></div>
<p>You should have got similar output to your test of MarkSweep above.</p>

<p>That's it.&nbsp; You're done. <img class="emoticon" src="images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<h1><a name="AddingaNewGC-"></a></h1>


<h1><a name="AddingaNewGC-MakingitPrettier"></a><b>Making it Prettier</b></h1>

<p>You may have noticed that when you cloned the package <em>org.mmtk.plan.marksweep</em>, all the classes retained their old names (although in your new namespace; <em>org.mmtk.plan.</em><b><em>mygc</em></b>).&nbsp; You can trivially change the class names in an IDE like eclipse.&nbsp; You can do the same with your favorite text editor, but you'll need to be sure that you change the references carefully.&nbsp; To change the class names in eclipse, just follow the procedure below for each class in <em>org.mmtk.plan.</em><b><em>mygc</em></b>:</p>
<ol>
	<li>Navigate to the class you want changed (eg&nbsp; <em>org.mmtk.plan.</em><b><em>mygc</em></b><em>.MS)</em></li>
	<li>Right click on the class (MS) and select <em>"Refactor-&gt;Rename..."</em> and then type in your new name, (eg <em>MyGC</em>)</li>
	<li><em>Do the same for each of the other classes:</em>&#35;&#42; <em>MS &#45;&gt; MyGC</em>#* <em>MSCollector &#45;&gt; MyGCCollector</em>
	<ul>
		<li><em>MSConstraints &#45;&gt; MyGCConstraints</em></li>
		<li><em>MSMutator &#45;&gt; MyGCMutator</em></li>
		<li><em>MSTraceLocal &#45;&gt; MyGCTraceLocal</em></li>
	</ul>
	</li>
	<li>Edit your configuration/s to ensure they refer to the renamed classes (since your IDE is unlikely to have done this automatically for you)
	<ul>
		<li>Go to <em>build/configs</em>, and edit each file <em>&#42;MyGC.properties</em> to refer to your renamed classes</li>
	</ul>
	</li>
</ol>


<h1><a name="AddingaNewGC-"></a></h1>


<h1><a name="AddingaNewGC-BeyondBaseBaseMyGC"></a>Beyond BaseBaseMyGC</h1>

<p>You probably want to build with configurations other than just BaseBase.&nbsp; If so, clone configurations from MarkSweep, just as you did above (for example, clone <em>FastAdaptiveMarkSweep</em> as <em>FastAdaptive</em><b><em>MyGC</em></b>).</p>

<h1><a name="AddingaNewGC-WhatNext%3F"></a>What Next?</h1>

<p>Once you have this working, you have successfully created and tested your own GC without writing a line of code&#33;&#33; You are ready to start the slightly more tricky process of writing your own garbage collector code.</p>

<p>If you are writing a new GC, you should definitely be aware of the MMTk <a href="The MMTk Test Harness.html" title="The MMTk Test Harness">test harness</a>, which allows you to test and debug MMTk in a very well contained pure Java environment, without the rest of Jikes RVM.&nbsp; This allows you to write unit tests and corner cases, and moreover, allows you to edit and debug MMTk entirely from within your IDE
<br class="atl-forced-newline" /></p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Jul 04, 2010 19:57</font></td>
		    </tr>
	    </table>
    </body>
</html>